All DatabasesInside Mac - Basic Toolbox
Adding Your Own Menu Items to the Help Menu
Adding Your Own Menu Items to the Help Menu
The Help menu is specific to each application, just as the File and
Edit menus are. The Help menu items defined by the Help Manager
should be common to all applications, but you can add your own menu
items for help-related information.
If you currently provide your users with help information when they
choose the About command from the Apple menu, you should instead
append a command for your own help to the Help menu. This gives
users one consistent place to obtain help information.
When adding your own items to the Help menu, include the name of
your application in the command so that users can easily determine
which application the help relates to. For example, the Figure below
shows the Help menu with two items appended to it by related
components of the same application.
The Help menu with two appended menu items
You add items to the Help menu by using the
HMGetHelpMenuHandle function and by providing an 'hmnu'
resource and specifying the kHMHelpMenuID constant as the resource
ID.
The HMGetHelpMenuHandle function returns a copy of the handle
to the Help menu. Do not use the GetMHandle function to get a handle
to the Help menu, because GetMHandle returns a handle to the global
Help menu, not the Help menu that is specific to your application.
Once you have a handle to the Help menu that is specific to your
application, you can add items to it using the AppendMenu procedure
or other Menu Manager routines. For example, this code adds the two
menu items displayed in the Figure above.
#include <Balloons.h>
void AddTwoMenuItems()
{
MenuHandle mh;
OSErr err;
err = HMGetHelpMenuHandle(&mh);
if ((err == noErr) && mh) {
AppendMenu (mh, "\p SurfWriter help");
AppendMenu (mh, "\p WipeOut help");
}
DrawMenuBar();
}
Be sure to use an 'hmnu' resource to provide help balloons for items
you've added to the Help menu. Use the kHMHelpMenuID constant
(-16490) to specify the 'hmnu' resource ID. After the header
component of the 'hmnu' resource, provide a missing items component
and then the components for your appended items. You do not provide a
menu title component here; instead, the Help Manager automatically
creates the help balloons for the Help menu title and the standard
Help menu items. The Help Manager automatically adds a dashed
line between the end of the standard Help menu items and your
appended items.
The following Listing shows an 'hmnu' resource for the appended
menu items shown in the Figure above.
#include "Types.r
#include "Balloons.r
resource 'hmnu' (kHMHelpMenuID, "Help", purgeable) {
HelpMgrVersion, 0, 0, 0, // header information
HMSkipItem { // missing items information
// no missing items, so skip to appended menu items
// information
},
{ // SurfWriter help command's help balloon content
HMStringResItem { // use an 'STR#' resource for content
146,1, // 'STR#' res ID, index when command's enabled
146,2, // 'STR#' res ID, index when dimmed
146,3, // 'STR#' res ID, index when command's checked
0,0 // command cannot be marked
},
// WipeOut help command's help balloon content
HMStringResItem { // use an 'STR#' resource for content
146,4, // 'STR#' res ID, index when command's enabled
146,5, // 'STR#' res ID, index when dimmed
146,6, // 'STR#' res ID, index when command's checked
0,0 // command cannot be marked
},
}
};
resource 'STR#' (146, "My Help menu items' strings") {
{ // array StringArray: 6 elements
// [1] enabled "SurfWriter help" command help text
"Displays tutorial help for SurfWriter word processor.";
// [2] dimmed "SurfWriter help" command help text
"Displays tutorial help for SurfWriter word processor.
"Not available until you open a SurfWriter document.";
// [3] checked "SurfWriter help" command help text
"Closes tutorial help for SurfWriter word processor.";
// [4] enabled "WipeOut help" command help text
"Displays tutorial help for WipeOut typing corrector.";
// [5] dimmed "WipeOut help" command help text
"Displays tutorial help for WipeOut typing corrector.
"Not available until you open a SurfWriter document.";
// [6] checked "WipeOut help" command help text
"Closes tutorial help for WipeOut typing corrector.";
}
};
The menu help resource that you create allows you to specify help
balloons for four states of a menu item: enabled, dimmed, enabled and
checked, and enabled and marked with a symbol other than a check. You
cannot specify a help balloon for a Help menu item when a modal
dialog box disables it, because you do not have access to the missing
items component of the Help menu. When a modal dialog box appears,
the Help Manager displays a default help balloon for all dimmed
Help menu items.
The Help Manager automatically processes the event when a user
chooses any of the standard menu items in the Help menu. The
Help Manager automatically enables and disables help when the
user chooses Show Balloons or Hide Balloons from the Help
menu. The setting of help is global and affects all applications.
The MenuSelect and MenuKey functions return a result with the
menu ID in the high word and the menu item in the low word of the
function result. Both functions return the kHMHelpMenuID constant
(-16490) in the high word when the user chooses an appended item
from the Help menu. The menu item number of the appended item is
returned in the low word of the function result. The MyMenuClick
procedure shown here handles mouse clicks for those items defined by
the application to appear in the Help menu.
#include <Balloons.h>
void MyMenuClick(long menuCode)
{
short menu;
short item;
WindowPtr window;
window = FrontWindow();
menu = HiWord(menuCode);
item = LoWord(menuCode);
switch (menu) {
case mApple:
// handle About box and other items
break;
case mFile:
FileClick( window,item);
break;
case mEdit:
EditClick( window,item);
break;
case mFonts:
FontClick( window,item);
break;
case kHMHelpMenuID:
HelpClick( window,item);
break;
}
HiliteMenu(0);
}
In the future, Apple may choose to add other items to the Help menu.
To determine the number of items in the Help menu, call the
CountMItems function, which is descibed in the Menu Manager.